Document use of grammars in template/expression context

[radeksimko]

History

The main context in which we expect HCL/Terraform grammars to be used is to highlight whole HCL "bodies". For example

attr = "foobar"
block "label" {
  another = 42
}
ref = data.aws_instance.foo.tags["noot"]

The "expression" on the RHS after the = is part of the existing grammars and we happen to treat standalone expressions, such as

42
"foobar"
data.aws_instance.foo.tags["noot"]

The decision to treat standalone expressions as valid was mostly pragmatic, where it was easier to do it than not to, due to the way TextMate grammars and nesting inside works.

To date however, this was a rather "hidden feature".

Potential

There are context in which this can be genuinely useful. For example:

• rendering full object structures in highlighted hover data (markdown), e.g. { foo = string, bar = set(number) }
• template files, which are effectively the inner part of a template expression, i.e. the ... in attr = "${...}" - see Support Color Syntax Highlighting for Templates (tmpl, etc) vscode-terraform#496 / meta: Support for Terraform files other than .tf vscode-terraform#636

Proposal

• Ensure we have this use case covered by tests
• Document this use case clearly in the Readme