deps: github.com/hashicorp/terraform@sdk-v0.11-with-go-modules

Updated via: go get github.com/hashicorp/terraform@sdk-v0.11-with-go-modules and go mod tidy

1 files changed, 923 insertions, 0 deletions

diff --git a/vendor/github.com/hashicorp/hcl2/hcl/hclsyntax/spec.md b/vendor/github.com/hashicorp/hcl2/hcl/hclsyntax/spec.md
new file mode 100644
index 0000000..49b9a3e
--- /dev/null
+++ b/vendor/github.com/hashicorp/hcl2/hcl/hclsyntax/spec.md
@@ -0,0 +1,923 @@
+# HCL Native Syntax Specification
+
+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 maintenence, as opposed to machine
+generation of configuration.
+
+The language consists of three integrated sub-languages:
+
+* The _structural_ language defines the overall heirarchical 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.
+
+## Syntax Notation
+
+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:
+
+* A naked name starting with an uppercase letter is a global production,
+  common to all of the syntax specifications in this document.
+* A naked name starting with a lowercase letter is a local production,
+  meaningful only within the specification where it is defined.
+* Double and single quotes (`"` and `'`) are used to mark literal character
+  sequences, which may be either punctuation markers or keywords.
+* The default operator for combining items, which has no punctuation,
+  is concatenation.
+* The symbol `|` indicates that any one of its left and right operands may
+  be present.
+* The `*` symbol indicates zero or more repetitions of the item to its left.
+* The `?` symbol indicates zero or one of the item to its left.
+* Parentheses (`(` 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 Representation
+
+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.
+
+## Lexical Elements
+
+### Comments and Whitespace
+
+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 not considered to be whitespace and
+are not valid within HCL native syntax.
+
+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 comments 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
+
+Identifiers name entities such as blocks, attributes and expression variables.
+Identifiers are interpreted as per [UAX #31][UAX31] Section 2. Specifically,
+their syntax is defined in terms of the `ID_Start` and `ID_Continue`
+character properties as follows:
+
+```ebnf
+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.
+
+[UAX31]: http://unicode.org/reports/tr31/ "Unicode Identifier and Pattern Syntax"
+
+### Keywords
+
+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.
+
+### Operators and Delimiters
+
+The following character sequences represent operators, delimiters, and other
+special tokens:
+
+```
++    &&   ==   <    :    {    [    (    ${
+-    ||   !=   >    ?    }    ]    )    %{
+*    !         <=        =         .
+/              >=        =>        ,
+%                                  ...
+```
+
+### Numeric Literals
+
+A numeric literal is a decimal representation of a
+real number. It has an integer part, a fractional part,
+and an exponent part.
+
+```ebnf
+NumericLit = decimal+ ("." decimal+)? (expmark decimal+)?;
+decimal    = '0' .. '9';
+expmark    = ('e' | 'E') ("+" | "-")?;
+```
+
+## Structural Elements
+
+The structural language consists of syntax representing the following
+constructs:
+
+* _Attributes_, which assign a value to a specified name.
+* _Blocks_, which create a child body annotated by a type and optional labels.
+* _Body Content_, which consists of a collection of attributes and blocks.
+
+These constructs correspond to the similarly-named concepts in the
+language-agnostic HCL information model.
+
+```ebnf
+ConfigFile = Body;
+Body       = (Attribute | Block)*;
+Attribute  = Identifier "=" Expression Newline;
+Block      = Identifier (StringLit|Identifier)* "{" Newline Body "}" Newline;
+```
+
+### Configuration Files
+
+A _configuration file_ is a sequence of characters whose top-level is
+interpreted as a Body.
+
+### Bodies
+
+A _body_ is a collection of associated attributes and blocks. The meaning of
+this association is defined by the calling application.
+
+### Attribute Definitions
+
+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.
+
+### Blocks
+
+A _block_ creates a child body that is annotated with a block _type_ and
+zero or more block _labels_. Blocks create a structural heirachy which can be
+interpreted by the calling application.
+
+Block labels can either be quoted literal strings or naked identifiers.
+
+## Expressions
+
+The expression sub-language is used within attribute definitions to specify
+values.
+
+```ebnf
+Expression = (
+    ExprTerm |
+    Operation |
+    Conditional
+);
+```
+
+### Types
+
+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
+
+Expression _terms_ are the operands for unary and binary expressions, as well
+as acting as expressions in their own right.
+
+```ebnf
+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.
+
+### Literal Values
+
+A _literal value_ immediately represents a particular value of a primitive
+type.
+
+```ebnf
+LiteralValue = (
+  NumericLit |
+  "true" |
+  "false" |
+  "null"
+);
+```
+
+* Numeric literals represent values of type _number_.
+* The `true` and `false` keywords represent values of type _bool_.
+* The `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_.
+
+### Collection Values
+
+A _collection value_ combines zero or more other expressions to produce a
+collection value.
+
+```ebnf
+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 is a reference to a variable named `for`. The
+_for expression_ interpretation has priority, so to produce a tuple whose
+first element is the value of a variable named `for`, or an object with a
+key named `for`, use paretheses 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.
+
+### Template Expressions
+
+A _template expression_ embeds a program written in the template sub-language
+as an expression. Template expressions come in two forms:
+
+* A _quoted_ template expression is delimited by quote characters (`"`) and
+  defines a template as a single-line expression with escape characters.
+* A _heredoc_ template expression is introduced by a `<<` 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.
+
+```ebnf
+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:
+
+```ebnf
+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.
+
+### Variables and Variable Expressions
+
+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:
+
+```ebnf
+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.
+
+### Functions and Function Calls
+
+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:
+
+```ebnf
+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.
+
+### For Expressions
+
+A _for expression_ is a construct for constructing a collection by projecting
+the items from another collection.
+
+```ebnf
+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:
+
+* For tuple and list types, the _key_ is the zero-based index into the
+  sequence for each element, and the _value_ is the element value. The
+  elements are visited in index order.
+* For object and map types, the _key_ is the string attribute name or element
+  key, and the _value_ is the attribute or element value. The elements are
+  visited in the order defined by a lexicographic sort of the attribute names
+  or keys.
+* For set types, the _key_ and _value_ are both the element value. The elements
+  are visited in an undefined but consistent order.
+
+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 experssion, 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"]: k => v}` 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.
+
+### Index Operator
+
+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.
+
+```ebnf
+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.
+
+### Attribute Access Operator
+
+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.
+
+```ebnf
+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.
+
+### Splat Operators
+
+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.
+
+```ebnf
+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 the left operand of a splat operator is an unknown value of any type, the
+result is a value of the dynamic pseudo-type.
+
+### Operations
+
+Operations apply a particular operator to either one or two expression terms.
+
+```ebnf
+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
+
+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
+
+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
+
+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.
+
+### Conditional Operator
+
+The conditional operator allows selecting from one of two expressions based on
+the outcome of a boolean expression.
+
+```ebnf
+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`.
+
+## Templates
+
+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.
+
+```ebnf
+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.
+
+### Template Literals
+
+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 literalsas 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.
+
+### Template Interpolations
+
+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.
+
+```ebnf
+TemplateInterpolation = ("${" | "${~") Expression ("}" | "~}";
+```
+
+If the expression result cannot be converted to a string, an error is
+produced.
+
+### Template If Directive
+
+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.
+
+```ebnf
+TemplateIf = (
+    ("%{" | "%{~") "if" Expression ("}" | "~}")
+    Template
+    (
+        ("%{" | "%{~") "else" ("}" | "~}")
+        Template
+    )?
+    ("%{" | "%{~") "endif" ("}" | "~}")
+);
+```
+
+The evaluation of the `if` directive is equivalent to the conditional
+expression, with the following exceptions:
+
+* The two sub-templates always produce strings, and thus the result value is
+  also always a string.
+* The `else` clause may be omitted, in which case the conditional's third
+  expression result is implied to be the empty string.
+
+### Template For Directive
+
+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.
+
+```ebnf
+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:
+
+* The sub-template always produces a string.
+* There is no equivalent of the "if" clause on the for expression.
+* The elements of the resulting tuple are all converted to strings and
+  concatenated to produce a flat string result.
+
+### Template Interpolation Unwrapping
+
+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}%{ endif }` 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.
+
+## Static Analysis
+
+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.
+
+### Static List
+
+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.
+
+### Static Map
+
+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 analyis, allowing callers to provide map-like
+constructs with different key types by building on the map syntax.
+
+### Static Call
+
+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.
+
+### Static Traversal
+
+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.