Support for built-in functions

[radeksimko]

Related to

• meta: Support all Terraform expression types #641
• Support built-in functions terraform-ls#37

---

Problem Statement

Terraform provides builtin functions to help users build reusable configuration.

Without consulting the documentation users may not always know:

• functions names available
• purpose of the function
• signature (arguments & outputs) of each function

Technical Details

Functions are considered to be expression types within HCL and each version of Terraform may contain different functions or the implementation of functions may differ.

User Impact

Any user which uses functions in their configuration would be impacted.

Expected User Experience

User will be guided to get names of functions, arguments and outputs right, and understand what a function does without leaving their editor.

Completion

Given a configuration

resource "aws_vpc" "example" {
  cidr_block = # HERE
}

when user requests completion in the highlighted position, aside from other candidates (such as references), they're presented with function names compatible with the field type (i.e. functions which return string in the above example as cidr_block is of type string):

• lower (string)
• upper (string)
• format (string, string...)

Hover

resource "aws_vpc" "example" {
  cidr_block = format("10.0.%d.0/%d", count.index, var.vpc_size)
}

When user hovers over format they're provided with a description of the function, such as:

format(spec, values...)

format produces a string by formatting a number of other values according to a specification string. It is similar to the printf function in C, and other similar functions in other programming languages.

https://www.terraform.io/docs/language/functions/format.html

Semantic highlighting

resource "aws_vpc" "example" {
  cidr_block = format("10.0.%d.0/%d", count.index, var.vpc_size)
}

The name of a valid function, such as format will be highlighted semantically as function name, name of an invalid function (such as frmt) will not. That way user can tell a difference between typo-ed function name and correct one just from the colours.

Function signature

resource "aws_vpc" "example" {
  cidr_block = format(

After picking function name from completion popup, or typing a "trigger character" ( user is presented with function signature. They're also presented with details relevant to an argument relevant to the position after typing (or completing) "trigger character" ,.

The user-visible content presented is similar to the one presented via hover, except that here we also document each parameter individually, i.e.

• spec string - The specification is a string that includes formatting verbs that are introduced with the % character.
• values string - Values to be formatted per specification

Proposal

• hcl-lang to allow registering function signatures, or whole functions (depending on implementation)
• terraform-schema to provide function signatures, or whole functions

Blocking Questions

• Do we want to decouple functions entirely from Terraform Core, maintain a copy somewhere, or provide a way for TF Core to expose functions?
  • This initially applies to just function names and their signatures, but longer term also likely implementations to support live interpolation to show users interpolated values per Show interpolated expression values on hover terraform-ls#495

[radeksimko]

Support for functions was implemented as part of the following PRs:

• Add function signature types hcl-lang#207
• decoder: Add support for AnyExpression as Constraint hcl-lang#232
• Add support for built-in functions terraform-schema#145
• Add support for function signature help terraform-ls#1077
• Add support for SignatureAtPos hcl-lang#135

This was all released as part of v0.31.0 which is already part of the preview extension and will be part of the next stable release (2.26.0) which is expected to land 🔜 .

There are some related issues to follow-up on which are being tracked separately:

• Link to docs for functions terraform-ls#1252
• Display function parameter description on hover terraform-ls#1248
• Improve the sorting order of completion items terraform-ls#1249
• Trigger signatureHelp when completing a function #1388
• decoder: Improve SignatureAtPos accuracy hcl-lang#235
• Use Markdown for signature help descriptions terraform-ls#1212
• Improve signature help for functions with similarly named parameters terraform-ls#1211

All the features shown in the initial post are however implemented, so I'm going to close this.

[github-actions]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.
If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.