This is the specification of the syntax and semantics of the native syntax for HCL. HCL is a system for defining configuration languages for applications. The HCL information model is designed to support multiple concrete syntaxes for configuration, but this native syntax is considered the primary format and is optimized for human authoring and maintenance, as opposed to machine generation of configuration.
The language consists of three integrated sub-languages:
The structural language defines the overall hierarchical configuration structure, and is a serialization of HCL bodies, blocks and attributes.
The expression language is used to express attribute values, either as literals or as derivations of other values.
The template language is used to compose values together into strings, as one of several types of expression in the expression language.
In normal use these three sub-languages are used together within configuration files to describe an overall configuration, with the structural language being used at the top level. The expression and template languages can also be used in isolation, to implement features such as REPLs, debuggers, and integration into more limited HCL syntaxes such as the JSON profile.
Within this specification a semi-formal notation is used to illustrate the details of syntax. This notation is intended for human consumption rather than machine consumption, with the following conventions:
" and ') are used to mark literal character sequences, which may be either punctuation markers or keywords.| indicates that any one of its left and right operands may be present.* symbol indicates zero or more repetitions of the item to its left.? symbol indicates zero or one of the item to its left.( and )) are used to group items together to apply the |, * and ? operators to them collectively.The grammar notation does not fully describe the language. The prose may augment or conflict with the illustrated grammar. In case of conflict, prose has priority.
Source code is unicode text expressed in the UTF-8 encoding. The language itself does not perform unicode normalization, so syntax features such as identifiers are sequences of unicode code points and so e.g. a precombined accented character is distinct from a letter associated with a combining accent. (String literals have some special handling with regard to Unicode normalization which will be covered later in the relevant section.)
UTF-8 encoded Unicode byte order marks are not permitted. Invalid or non-normalized UTF-8 encoding is always a parse error.
Comments and Whitespace are recognized as lexical elements but are ignored except as described below.
Whitespace is defined as a sequence of zero or more space characters (U+0020). Newline sequences (either U+000A or U+000D followed by U+000A) are not considered whitespace but are ignored as such in certain contexts. Horizontal tab characters (U+0009) are also treated as whitespace, but are counted only as one “column” for the purpose of reporting source positions.
Comments serve as program documentation and come in two forms:
Line comments start with either the // or # sequences and end with the next newline sequence. A line comment is considered equivalent to a newline sequence.
Inline comments start with the /* sequence and end with the */ sequence, and may have any characters within except the ending sequence. An inline comments is considered equivalent to a whitespace sequence.
Comments and whitespace cannot begin within within other comments, or within template literals except inside an interpolation sequence or template directive.
Identifiers name entities such as blocks, attributes and expression variables. Identifiers are interpreted as per UAX #31 Section 2. Specifically, their syntax is defined in terms of the ID_Start and ID_Continue character properties as follows:
Identifier = ID_Start (ID_Continue | '-')*;
The Unicode specification provides the normative requirements for identifier parsing. Non-normatively, the spirit of this specification is that ID_Start consists of Unicode letter and certain unambiguous punctuation tokens, while ID_Continue augments that set with Unicode digits, combining marks, etc.
The dash character - is additionally allowed in identifiers, even though that is not part of the unicode ID_Continue definition. This is to allow attribute names and block type names to contain dashes, although underscores as word separators are considered the idiomatic usage.
There are no globally-reserved words, but in some contexts certain identifiers are reserved to function as keywords. These are discussed further in the relevant documentation sections that follow. In such situations, the identifier's role as a keyword supersedes any other valid interpretation that may be possible. Outside of these specific situations, the keywords have no special meaning and are interpreted as regular identifiers.
The following character sequences represent operators, delimiters, and other special tokens:
+ && == < : { [ ( ${
- || != > ? } ] ) %{
* ! <= = .
/ >= => ,
% ...
A numeric literal is a decimal representation of a real number. It has an integer part, a fractional part, and an exponent part.
NumericLit = decimal+ ("." decimal+)? (expmark decimal+)?; decimal = '0' .. '9'; expmark = ('e' | 'E') ("+" | "-")?;
The structural language consists of syntax representing the following constructs:
These constructs correspond to the similarly-named concepts in the language-agnostic HCL information model.
ConfigFile = Body; Body = (Attribute | Block | OneLineBlock)*; Attribute = Identifier "=" Expression Newline; Block = Identifier (StringLit|Identifier)* "{" Newline Body "}" Newline; OneLineBlock = Identifier (StringLit|Identifier)* "{" (Identifier "=" Expression)? "}" Newline;
A configuration file is a sequence of characters whose top-level is interpreted as a Body.
A body is a collection of associated attributes and blocks. The meaning of this association is defined by the calling application.
An attribute definition assigns a value to a particular attribute name within a body. Each distinct attribute name may be defined no more than once within a single body.
The attribute value is given as an expression, which is retained literally for later evaluation by the calling application.
A block creates a child body that is annotated with a block type and zero or more block labels. Blocks create a structural hierarchy which can be interpreted by the calling application.
Block labels can either be quoted literal strings or naked identifiers.
The expression sub-language is used within attribute definitions to specify values.
Expression = ( ExprTerm | Operation | Conditional );
The value types used within the expression language are those defined by the syntax-agnostic HCL information model. An expression may return any valid type, but only a subset of the available types have first-class syntax. A calling application may make other types available via variables and functions.
Expression terms are the operands for unary and binary expressions, as well as acting as expressions in their own right.
ExprTerm = ( LiteralValue | CollectionValue | TemplateExpr | VariableExpr | FunctionCall | ForExpr | ExprTerm Index | ExprTerm GetAttr | ExprTerm Splat | "(" Expression ")" );
The productions for these different term types are given in their corresponding sections.
Between the ( and ) characters denoting a sub-expression, newline characters are ignored as whitespace.
A literal value immediately represents a particular value of a primitive type.
LiteralValue = ( NumericLit | "true" | "false" | "null" );
true and false keywords represent values of type bool.null keyword represents a null value of the dynamic pseudo-type.String literals are not directly available in the expression sub-language, but are available via the template sub-language, which can in turn be incorporated via template expressions.
A collection value combines zero or more other expressions to produce a collection value.
CollectionValue = tuple | object; tuple = "[" ( (Expression ("," Expression)* ","?)? ) "]"; object = "{" ( (objectelem ("," objectelem)* ","?)? ) "}"; objectelem = (Identifier | Expression) ("=" | ":") Expression;
Only tuple and object values can be directly constructed via native syntax. Tuple and object values can in turn be converted to list, set and map values with other operations, which behaves as defined by the syntax-agnostic HCL information model.
When specifying an object element, an identifier is interpreted as a literal attribute name as opposed to a variable reference. To populate an item key from a variable, use parentheses to disambiguate:
{foo = "baz"} is interpreted as an attribute literally named foo.{(foo) = "baz"} is interpreted as an attribute whose name is taken from the variable named foo.Between the open and closing delimiters of these sequences, newline sequences are ignored as whitespace.
There is a syntax ambiguity between for expressions and collection values whose first element starts with an identifier named for. The for expression interpretation has priority, so to write a key literally named for or an expression derived from a variable named for you must use parentheses or quotes to disambiguate:
[for, foo, baz] is a syntax error.[(for), foo, baz] is a tuple whose first element is the value of variable for.{for = 1, baz = 2} is a syntax error.{"for" = 1, baz = 2} is an object with an attribute literally named for.{baz = 2, for = 1} is equivalent to the previous example, and resolves the ambiguity by reordering.{(for) = 1, baz = 2} is an object with a key with the same value as the variable for.A template expression embeds a program written in the template sub-language as an expression. Template expressions come in two forms:
") and defines a template as a single-line expression with escape characters.<< sequence and defines a template via a multi-line sequence terminated by a user-chosen delimiter.In both cases the template interpolation and directive syntax is available for use within the delimiters, and any text outside of these special sequences is interpreted as a literal string.
In quoted template expressions any literal string sequences within the template behave in a special way: literal newline sequences are not permitted and instead escape sequences can be included, starting with the backslash \:
\n Unicode newline control character
\r Unicode carriage return control character
\t Unicode tab control character
\" Literal quote mark, used to prevent interpretation as end of string
\\ Literal backslash, used to prevent interpretation as escape sequence
\uNNNN Unicode character from Basic Multilingual Plane (NNNN is four hexadecimal digits)
\UNNNNNNNN Unicode character from supplementary planes (NNNNNNNN is eight hexadecimal digits)
The heredoc template expression type is introduced by either << or <<-, followed by an identifier. The template expression ends when the given identifier subsequently appears again on a line of its own.
If a heredoc template is introduced with the <<- symbol, any literal string at the start of each line is analyzed to find the minimum number of leading spaces, and then that number of prefix spaces is removed from all line-leading literal strings. The final closing marker may also have an arbitrary number of spaces preceding it on its line.
TemplateExpr = quotedTemplate | heredocTemplate; quotedTemplate = (as defined in prose above); heredocTemplate = ( ("<<" | "<<-") Identifier Newline (content as defined in prose above) Identifier Newline );
A quoted template expression containing only a single literal string serves as a syntax for defining literal string expressions. In certain contexts the template syntax is restricted in this manner:
StringLit = '"' (quoted literals as defined in prose above) '"';
The StringLit production permits the escape sequences discussed for quoted template expressions as above, but does not permit template interpolation or directive sequences.
A variable is a value that has been assigned a symbolic name. Variables are made available for use in expressions by the calling application, by populating the global scope used for expression evaluation.
Variables can also be created by expressions themselves, which always creates a child scope that incorporates the variables from its parent scope but (re-)defines zero or more names with new values.
The value of a variable is accessed using a variable expression, which is a standalone Identifier whose name corresponds to a defined variable:
VariableExpr = Identifier;
Variables in a particular scope are immutable, but child scopes may hide a variable from an ancestor scope by defining a new variable of the same name. When looking up variables, the most locally-defined variable of the given name is used, and ancestor-scoped variables of the same name cannot be accessed.
No direct syntax is provided for declaring or assigning variables, but other expression constructs implicitly create child scopes and define variables as part of their evaluation.
A function is an operation that has been assigned a symbolic name. Functions are made available for use in expressions by the calling application, by populating the function table used for expression evaluation.
The namespace of functions is distinct from the namespace of variables. A function and a variable may share the same name with no implication that they are in any way related.
A function can be executed via a function call expression:
FunctionCall = Identifier "(" arguments ")"; Arguments = ( () || (Expression ("," Expression)* ("," | "...")?) );
The definition of functions and the semantics of calling them are defined by the language-agnostic HCL information model. The given arguments are mapped onto the function's parameters and the result of a function call expression is the return value of the named function when given those arguments.
If the final argument expression is followed by the ellipsis symbol (...), the final argument expression must evaluate to either a list or tuple value. The elements of the value are each mapped to a single parameter of the named function, beginning at the first parameter remaining after all other argument expressions have been mapped.
Within the parentheses that delimit the function arguments, newline sequences are ignored as whitespace.
A for expression is a construct for constructing a collection by projecting the items from another collection.
ForExpr = forTupleExpr | forObjectExpr; forTupleExpr = "[" forIntro Expression forCond? "]"; forObjectExpr = "{" forIntro Expression "=>" Expression "..."? forCond? "}"; forIntro = "for" Identifier ("," Identifier)? "in" Expression ":"; forCond = "if" Expression;
The punctuation used to delimit a for expression decide whether it will produce a tuple value ([ and ]) or an object value ({ and }).
The “introduction” is equivalent in both cases: the keyword for followed by either one or two identifiers separated by a comma which define the temporary variable names used for iteration, followed by the keyword in and then an expression that must evaluate to a value that can be iterated. The introduction is then terminated by the colon (:) symbol.
If only one identifier is provided, it is the name of a variable that will be temporarily assigned the value of each element during iteration. If both are provided, the first is the key and the second is the value.
Tuple, object, list, map, and set types are iterable. The type of collection used defines how the key and value variables are populated:
The expression after the colon and (in the case of object for) the expression after the => are both evaluated once for each element of the source collection, in a local scope that defines the key and value variable names specified.
The results of evaluating these expressions for each input element are used to populate an element in the new collection. In the case of tuple for, the single expression becomes an element, appending values to the tuple in visit order. In the case of object for, the pair of expressions is used as an attribute name and value respectively, creating an element in the resulting object.
In the case of object for, it is an error if two input elements produce the same result from the attribute name expression, since duplicate attributes are not possible. If the ellipsis symbol (...) appears immediately after the value expression, this activates the grouping mode in which each value in the resulting object is a tuple of all of the values that were produced against each distinct key.
[for v in ["a", "b"]: v] returns ["a", "b"].[for i, v in ["a", "b"]: i] returns [0, 1].{for i, v in ["a", "b"]: v => i} returns {a = 0, b = 1}.{for i, v in ["a", "a", "b"]: v => i} produces an error, because attribute a is defined twice.{for i, v in ["a", "a", "b"]: v => i...} returns {a = [0, 1], b = [2]}.If the if keyword is used after the element expression(s), it applies an additional predicate that can be used to conditionally filter elements from the source collection from consideration. The expression following if is evaluated once for each source element, in the same scope used for the element expression(s). It must evaluate to a boolean value; if true, the element will be evaluated as normal, while if false the element will be skipped.
[for i, v in ["a", "b", "c"]: v if i < 2] returns ["a", "b"].If the collection value, element expression(s) or condition expression return unknown values that are otherwise type-valid, the result is a value of the dynamic pseudo-type.
The index operator returns the value of a single element of a collection value. It is a postfix operator and can be applied to any value that has a tuple, object, map, or list type.
Index = "[" Expression "]";
The expression delimited by the brackets is the key by which an element will be looked up.
If the index operator is applied to a value of tuple or list type, the key expression must be an non-negative integer number representing the zero-based element index to access. If applied to a value of object or map type, the key expression must be a string representing the attribute name or element key. If the given key value is not of the appropriate type, a conversion is attempted using the conversion rules from the HCL syntax-agnostic information model.
An error is produced if the given key expression does not correspond to an element in the collection, either because it is of an unconvertable type, because it is outside the range of elements for a tuple or list, or because the given attribute or key does not exist.
If either the collection or the key are an unknown value of an otherwise-suitable type, the return value is an unknown value whose type matches what type would be returned given known values, or a value of the dynamic pseudo-type if type information alone cannot determine a suitable return type.
Within the brackets that delimit the index key, newline sequences are ignored as whitespace.
The HCL native syntax also includes a legacy index operator that exists only for compatibility with the precursor language HIL:
LegacyIndex = '.' digit+
This legacy index operator must be supported by parser for compatibility but should not be used in new configurations. This allows an attribute-access-like syntax for indexing, must still be interpreted as an index operation rather than attribute access.
The legacy syntax does not support chaining of index operations, like foo.0.0.bar, because the interpretation of 0.0 as a number literal token takes priority and thus renders the resulting sequence invalid.
The attribute access operator returns the value of a single attribute in an object value. It is a postfix operator and can be applied to any value that has an object type.
GetAttr = "." Identifier;
The given identifier is interpreted as the name of the attribute to access. An error is produced if the object to which the operator is applied does not have an attribute with the given name.
If the object is an unknown value of a type that has the attribute named, the result is an unknown value of the attribute's type.
The splat operators allow convenient access to attributes or elements of elements in a tuple, list, or set value.
There are two kinds of “splat” operator:
The attribute-only splat operator supports only attribute lookups into the elements from a list, but supports an arbitrary number of them.
The full splat operator additionally supports indexing into the elements from a list, and allows any combination of attribute access and index operations.
Splat = attrSplat | fullSplat; attrSplat = "." "*" GetAttr*; fullSplat = "[" "*" "]" (GetAttr | Index)*;
The splat operators can be thought of as shorthands for common operations that could otherwise be performed using for expressions:
tuple.*.foo.bar[0] is approximately equivalent to [for v in tuple: v.foo.bar][0].tuple[*].foo.bar[0] is approximately equivalent to [for v in tuple: v.foo.bar[0]]Note the difference in how the trailing index operator is interpreted in each case. This different interpretation is the key difference between the attribute-only and full splat operators.
Splat operators have one additional behavior compared to the equivalent for expressions shown above: if a splat operator is applied to a value that is not of tuple, list, or set type, the value is coerced automatically into a single-value list of the value type:
any_object.*.id is equivalent to [any_object.id], assuming that any_object is a single object.any_number.* is equivalent to [any_number], assuming that any_number is a single number.If applied to a null value that is not tuple, list, or set, the result is always an empty tuple, which allows conveniently converting a possibly-null scalar value into a tuple of zero or one elements. It is illegal to apply a splat operator to a null value of tuple, list, or set type.
Operations apply a particular operator to either one or two expression terms.
Operation = unaryOp | binaryOp; unaryOp = ("-" | "!") ExprTerm; binaryOp = ExprTerm binaryOperator ExprTerm; binaryOperator = compareOperator | arithmeticOperator | logicOperator; compareOperator = "==" | "!=" | "<" | ">" | "<=" | ">="; arithmeticOperator = "+" | "-" | "*" | "/" | "%"; logicOperator = "&&" | "||" | "!";
The unary operators have the highest precedence.
The binary operators are grouped into the following precedence levels:
Level Operators 6 * / % 5 + - 4 > >= < <= 3 == != 2 && 1 ||
Higher values of “level” bind tighter. Operators within the same precedence level have left-to-right associativity. For example, x / y * z is equivalent to (x / y) * z.
Comparison operators always produce boolean values, as a result of testing the relationship between two values.
The two equality operators apply to values of any type:
a == b equal a != b not equal
Two values are equal if the are of identical types and their values are equal as defined in the HCL syntax-agnostic information model. The equality operators are commutative and opposite, such that (a == b) == !(a != b) and (a == b) == (b == a) for all values a and b.
The four numeric comparison operators apply only to numbers:
a < b less than a <= b less than or equal to a > b greater than a >= b greater than or equal to
If either operand of a comparison operator is a correctly-typed unknown value or a value of the dynamic pseudo-type, the result is an unknown boolean.
Arithmetic operators apply only to number values and always produce number values as results.
a + b sum (addition) a - b difference (subtraction) a * b product (multiplication) a / b quotient (division) a % b remainder (modulo) -a negation
Arithmetic operations are considered to be performed in an arbitrary-precision number space.
If either operand of an arithmetic operator is an unknown number or a value of the dynamic pseudo-type, the result is an unknown number.
Logic operators apply only to boolean values and always produce boolean values as results.
a && b logical AND a || b logical OR !a logical NOT
If either operand of a logic operator is an unknown bool value or a value of the dynamic pseudo-type, the result is an unknown bool value.
The conditional operator allows selecting from one of two expressions based on the outcome of a boolean expression.
Conditional = Expression "?" Expression ":" Expression;
The first expression is the predicate, which is evaluated and must produce a boolean result. If the predicate value is true, the result of the second expression is the result of the conditional. If the predicate value is false, the result of the third expression is the result of the conditional.
The second and third expressions must be of the same type or must be able to unify into a common type using the type unification rules defined in the HCL syntax-agnostic information model. This unified type is the result type of the conditional, with both expressions converted as necessary to the unified type.
If the predicate is an unknown boolean value or a value of the dynamic pseudo-type then the result is an unknown value of the unified type of the other two expressions.
If either the second or third expressions produce errors when evaluated, these errors are passed through only if the erroneous expression is selected. This allows for expressions such as length(some_list) > 0 ? some_list[0] : default (given some suitable length function) without producing an error when the predicate is false.
The template sub-language is used within template expressions to concisely combine strings and other values to produce other strings. It can also be used in isolation as a standalone template language.
Template = ( TemplateLiteral | TemplateInterpolation | TemplateDirective )* TemplateDirective = TemplateIf | TemplateFor;
A template behaves like an expression that always returns a string value. The different elements of the template are evaluated and combined into a single string to return. If any of the elements produce an unknown string or a value of the dynamic pseudo-type, the result is an unknown string.
An important use-case for standalone templates is to enable the use of expressions in alternative HCL syntaxes where a native expression grammar is not available. For example, the HCL JSON profile treats the values of JSON strings as standalone templates when attributes are evaluated in expression mode.
A template literal is a literal sequence of characters to include in the resulting string. When the template sub-language is used standalone, a template literal can contain any unicode character, with the exception of the sequences that introduce interpolations and directives, and for the sequences that escape those introductions.
The interpolation and directive introductions are escaped by doubling their leading characters. The ${ sequence is escaped as $${ and the %{ sequence is escaped as %%{.
When the template sub-language is embedded in the expression language via template expressions, additional constraints and transforms are applied to template literals as described in the definition of template expressions.
The value of a template literal can be modified by strip markers in any interpolations or directives that are adjacent to it. A strip marker is a tilde (~) placed immediately after the opening { or before the closing } of a template sequence:
hello ${~ "world" } produces "helloworld".%{ if true ~} hello %{~ endif } produces "hello".When a strip marker is present, any spaces adjacent to it in the corresponding string literal (if any) are removed before producing the final value. Space characters are interpreted as per Unicode's definition.
Stripping is done at syntax level rather than value level. Values returned by interpolations or directives are not subject to stripping:
${"hello" ~}${" world"} produces "hello world", and not "helloworld", because the space is not in a template literal directly adjacent to the strip marker.An interpolation sequence evaluates an expression (written in the expression sub-language), converts the result to a string value, and replaces itself with the resulting string.
TemplateInterpolation = ("${" | "${~") Expression ("}" | "~}";
If the expression result cannot be converted to a string, an error is produced.
The template if directive is the template equivalent of the conditional expression, allowing selection of one of two sub-templates based on the value of a predicate expression.
TemplateIf = ( ("%{" | "%{~") "if" Expression ("}" | "~}") Template ( ("%{" | "%{~") "else" ("}" | "~}") Template )? ("%{" | "%{~") "endif" ("}" | "~}") );
The evaluation of the if directive is equivalent to the conditional expression, with the following exceptions:
else clause may be omitted, in which case the conditional's third expression result is implied to be the empty string.The template for directive is the template equivalent of the for expression, producing zero or more copies of its sub-template based on the elements of a collection.
TemplateFor = ( ("%{" | "%{~") "for" Identifier ("," Identifier) "in" Expression ("}" | "~}") Template ("%{" | "%{~") "endfor" ("}" | "~}") );
The evaluation of the for directive is equivalent to the for expression when producing a tuple, with the following exceptions:
As a special case, a template that consists only of a single interpolation, with no surrounding literals, directives or other interpolations, is “unwrapped”. In this case, the result of the interpolation expression is returned verbatim, without conversion to string.
This special case exists primarily to enable the native template language to be used inside strings in alternative HCL syntaxes that lack a first-class template or expression syntax. Unwrapping allows arbitrary expressions to be used to populate attributes when strings in such languages are interpreted as templates.
${true} produces the boolean value true${"${true}"} produces the boolean value true, because both the inner and outer interpolations are subject to unwrapping.hello ${true} produces the string "hello true"${""}${true} produces the string "true" because there are two interpolation sequences, even though one produces an empty result.%{ for v in [true] }${v}%{ endfor } produces the string true because the presence of the for directive circumvents the unwrapping even though the final result is a single value.In some contexts this unwrapping behavior may be circumvented by the calling application, by converting the final template result to string. This is necessary, for example, if a standalone template is being used to produce the direct contents of a file, since the result in that case must always be a string.
The HCL static analysis operations are implemented for some expression types in the native syntax, as described in the following sections.
A goal for static analysis of the native syntax is for the interpretation to be as consistent as possible with the dynamic evaluation interpretation of the given expression, though some deviations are intentionally made in order to maximize the potential for analysis.
The tuple construction syntax can be interpreted as a static list. All of the expression elements given are returned as the static list elements, with no further interpretation.
The object construction syntax can be interpreted as a static map. All of the key/value pairs given are returned as the static pairs, with no further interpretation.
The usual requirement that an attribute name be interpretable as a string does not apply to this static analysis, allowing callers to provide map-like constructs with different key types by building on the map syntax.
The function call syntax can be interpreted as a static call. The called function name is returned verbatim and the given argument expressions are returned as the static arguments, with no further interpretation.
A variable expression and any attached attribute access operations and constant index operations can be interpreted as a static traversal.
The keywords true, false and null can also be interpreted as static traversals, behaving as if they were references to variables of those names, to allow callers to redefine the meaning of those keywords in certain contexts.