Support built-in functions

[radeksimko]

Background

Terraform configuration language has a number of built-in functions, some of which come from HCL.

Proposal - UX/LSP

Name Completion

When a user requests completion on the RHS (after "="), aside from other candidates (such as references), they're presented with function names compatible with the attribute type, i.e. functions which return string (or "any type") if the attribute is of type string.

Argument Completion

When the user confirms the function name from completion or types the opening brace, they are provided with any references of the argument type, i.e. if the argument being completed is of string type, then any references of string type are provided.

Hover

When the user hovers over the function name, they are provided with the signature of the function, brief description and link to the documentation for that function.

Semantic Tokens

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 users can tell the difference between typo-ed function name and correct one just from the colours.

Implementation Notes

• zclconf/go-cty
  • Introduce Description to the Spec and Parameter types of zclconf/go-cty/function
  • Backfill descriptions of functions & args in cty stdlib from docs
• hashicorp/terraform
  • Backfill descriptions of functions & args in Terraform Core from docs to enable signatures to be exposed via CLI later
• hashicorp/terraform-schema
  • Introduce Signature (see below) to terraform-schema to loosely mimic cty's function.Spec
  • Codify all TF functions for 0.12+ versions into terraform-schema/internal/funcs/functions.go using the Signature type; see prototype for finding return types
  • Expose FunctionsForVersion(v *version.Version) (map[string]Signature, error) from terraform-schema/schema
• hashicorp/hcl-lang
  • Add Functions map[string]function.Function to PathContext in hcl-lang
  • Update PathDecoder.CandidatesAtPos in hcl-lang/decoder
  • Update PathDecoder.HoverAtPos in hcl-lang/decoder
  • Update PathDecoder.SemanticTokensInFile in hcl-lang/decoder
• hashicorp/terraform-ls
  • Call new public schema.FunctionsForVersion() from within the internal/decoder package
  • Introduce a new handler for textDocument/signatureHelp which calls the new PathDecoder.SignatureAtPos() method

type FuncSignature struct {
   Name            string
   Description     lang.MarkupContent
   Parameters      []FuncParameter
   ActiveParameter uint
}
 
type FuncParameter struct {
   Name        string
   Description lang.MarkupContent
}

type Signature struct {
   Params      []function.Parameter
   VarParam    *function.Parameter
   ReturnTypes []cty.Type
   Description string
}

[danishprakash]

@radeksimko sorry for the noise but is this something I can work on? thanks

[radeksimko]

This will involve some upfront work on Terraform Core (to expose functions in some way) and drafting of the design (weighing pros and cons of different approaches), so it's probably not the best issue to pick for someone outside of HashiCorp at this point.

It is possible that once the upstream work is finished we could use some extra hands. It is unlikely that there will be progress on this particular issue in the next 3 weeks though.

[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 #1077
• Add support for SignatureAtPos hcl-lang#135

This was all released as part of v0.31.0.

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

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

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

[github-actions]

This functionality has been released in v0.31.0 of the language server.

For further feature requests or bug reports with this functionality, please create a new GitHub issue following the template. Thank you!

[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.