Skip to content

Commit

Permalink
add docs
Browse files Browse the repository at this point in the history
  • Loading branch information
radeksimko committed Mar 17, 2022
1 parent 8e76736 commit 9e7d58e
Show file tree
Hide file tree
Showing 2 changed files with 80 additions and 0 deletions.
4 changes: 4 additions & 0 deletions docs/language-clients.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,10 @@ Clients specifically should **not** send `*.tf.json`, `*.tfvars.json` nor
Packer HCL config nor any other HCL config files as the server is not
equipped to handle these file types.

## Syntax Highlighting

Read more about how we recommend Terraform files to be highlighted in [syntax-highlighting.md](./syntax-highlighting.md).

### Internal parser

The server expects clients to use standard text synchronization LSP methods
Expand Down
76 changes: 76 additions & 0 deletions docs/syntax-highlighting.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
# Syntax Highlighting

Highlighting syntax is one of the key features expected of any editor. Editors typically have a few different solutions to choose from. Below is our view on how we expect editors to highlight Terraform code while using this language server.

## Static Grammar

Highlighting Terraform language syntax via static grammar (such as TextMate) _accurately_ may be challenging but brings more immediate value to the end user, since starting language server may take time. Also not all language clients may implement semantic token based highlighting.

HashiCorp maintains a set of grammars in https://github.com/hashicorp/syntax and we encourage you to use the available Terraform grammar as the *primary* way of highlighting the Terraform language.

## Semantic Tokens

[LSP (Language Server Protocol) 3.16](https://microsoft.github.io/language-server-protocol/specifications/specification-3-16/) introduced language server-driven highlighting. This language server is better equipped to provide more contextual and accurate highlighting as it can parse the whole AST, unlike a TextMate grammar operating on a regex-basis.

LSP 3.17 does support use cases where semantic highlighting is the only way to highlight a file (through [`augmentsSyntaxTokens` client capability](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#semanticTokensClientCapabilities)). However in the context of the Terraform language we recommend semantic highlighting to be used as in *addition* to a static grammar - i.e. this server does _not_ support `augmentsSyntaxTokens: false` mode and is not expected to be used in isolation to highlight configuration.

There are two main use cases we're targeting with semantic tokens.

### Improving Accuracy

Regex-based grammars (like TextMate) operate on line-basis, which makes it difficult to accurately highlight nested blocks occuring in the Terraform language, such as below.

```hcl
terraform {
required_providers {
}
}
```

### Custom Theme Support

Many _default_ IDE themes are intended as general-purpose themes, highlighting token types, modifiers and scopes mappable to most languages. We recognize that theme authors would benefit from token types & modifiers which more accurately reflect the Terraform language.

LSP spec doesn't _explicitly_ encourage defining custom token types or modifiers, however the default token types and modifiers which are part of the spec are not well suited to express all the different constructs of a DSL (Domain Specific Language), such as Terraform language. With that in mind we use the LSP client/server capability negotiation mechanism to provide the following custom token types & modifiers with fallback to the predefined ones.

#### Token Types

Primary token types are preferred if deemed supported by client per `SemanticTokensClientCapabilities.TokenTypes`, fallbacks are also only reported if client claim support (using the same capability).

| Primary | Fallback |
| ------- | -------- |
| `hcl-blockType` | `type` |
| `hcl-blockLabel` | `enumMember` |
| `hcl-attrName` | `property` |
| `hcl-bool` | `keyword` |
| `hcl-number` | `number` |
| `hcl-string` | `string` |
| `hcl-objectKey` | `parameter` |
| `hcl-mapKey` | `parameter` |
| `hcl-keyword` | `variable` |
| `hcl-traversalStep` | `variable` |
| `hcl-typeCapsule` | `function` |
| `hcl-typePrimitive` | `keyword` |

#### Token Modifiers

Modifiers which do not have fallback are not reported at all if not received within `SemanticTokensClientCapabilities.TokenModifiers` (just like fallback modifier that isn't supported).

| Primary | Fallback |
| ------- | -------- |
| `hcl-dependent` | `defaultLibrary` |
| `terraform-data` | |
| `terraform-locals` | |
| `terraform-module` | |
| `terraform-output` | |
| `terraform-provider` | |
| `terraform-resource` | |
| `terraform-provisioner` | |
| `terraform-connection` | |
| `terraform-variable` | |
| `terraform-terraform` | |
| `terraform-backend` | |
| `terraform-name` | |
| `terraform-type` | |
| `terraform-requiredProviders` | |

0 comments on commit 9e7d58e

Please sign in to comment.