diff --git a/book/src/guides/adding_languages.md b/book/src/guides/adding_languages.md index 0cd6c27bbab62..e3a0ed0732c29 100644 --- a/book/src/guides/adding_languages.md +++ b/book/src/guides/adding_languages.md @@ -16,14 +16,15 @@ injection-regex = "^mylang$" file-types = ["mylang", "myl"] comment-token = "#" indent = { tab-width = 2, unit = " " } -language-server = { command = "mylang-lsp", args = ["--stdio"] } +language-servers = [ "mylang-lsp" ] ``` -These are the available keys and descriptions for the file. +These are the available keys and descriptions for a language. | Key | Description | | ---- | ----------- | | `name` | The name of the language | +| `language-id` | The language-id for language servers, checkout the table at [TextDocumentItem](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocumentItem) for the right id | | `scope` | A string like `source.js` that identifies the language. Currently, we strive to match the scope names used by popular TextMate grammars and by the Linguist library. Usually `source.` or `text.` in case of markup languages | | `injection-regex` | regex pattern that will be tested against a language name in order to determine whether this language should be used for a potential [language injection][treesitter-language-injection] site. | | `file-types` | The filetypes of the language, for example `["yml", "yaml"]`. Extensions and full file names are supported. | @@ -33,10 +34,76 @@ These are the available keys and descriptions for the file. | `diagnostic-severity` | Minimal severity of diagnostic for it to be displayed. (Allowed values: `Error`, `Warning`, `Info`, `Hint`) | | `comment-token` | The token to use as a comment-token | | `indent` | The indent to use. Has sub keys `tab-width` and `unit` | -| `language-server` | The Language Server to run. Has sub keys `command` and `args` | -| `config` | Language Server configuration | +| `language-servers` | The Language Servers used for this language. See below for more information | | `grammar` | The tree-sitter grammar to use (defaults to the value of `name`) | + +In case multiple language servers are specified, it's often useful to only enable certain language-server features for these language servers. +For example `efm-lsp-prettier` (see in the next section for an example configuration for typescript) is used only with a formatting command `prettier` +but everything else should be handled by the `typescript-language-server` (configured by default) +The language configuration for typescript could look like this: + +```toml +[[language]] +name = "typescript" +language-servers = [ { name = "efm-lsp-prettier", only-features = [ "format" ] }, "typescript-language-server" ] +``` + +or equivalent: + +```toml +[[language]] +name = "typescript" +language-servers = [ { name = "typescript-language-server", except-features = [ "format" ] }, "efm-lsp-prettier" ] +``` + +Each requested LSP feature is priorized in the order of the `language-servers` array. + +The list of supported features are: + +- `format` +- `goto-definition` +- `goto-type-definition` +- `goto-reference` +- `goto-implementation` +- `signature-help` +- `hover` +- `completion` +- `code-action` +- `document-symbols` +- `workspace-symbols` +- `diagnostics` +- `rename-symbol` + + +### Language server configuration + +Language servers are configured separately in the table `language-server` in the same file as the languages [`languages.toml`][languages.toml] + + +```toml +[langauge-server.mylang-lsp] +command = "mylang-lsp" +args = ["--stdio"] +config = { provideFormatter = true } + +[language-server.efm-lsp-prettier] +command = "efm-langserver" + +[language-server.efm-lsp-prettier.config] +documentFormatting = true +languages = { typescript = [ { formatCommand ="prettier --stdin-filepath ${INPUT}", formatStdin = true } ] } +``` + +These are the available keys and descriptions for a language server. + +| Key | Description | +| ---- | ----------- | +| `command` | The command for the language server | +| `args` | Arguments for the command | +| `config` | Language Server configuration | +| `timeout` | Timeout in seconds (default 20) for requests to the language server | + When adding a new language or Language Server configuration for an existing language, run `cargo xtask docgen` to add the new configuration to the [Language Support][lang-support] docs before creating a pull request.